<!--

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<html>
<body>
    <h1>SQL Objects</h1>
    <p>
        The sql objects API allows for declarative definition of interfaces which will handle
        the generation of sql statements and queries on your behalf when needed. Take the following interface:
    </p>
    <code>
        public interface TheBasics
        {
            {@literal @}SqlUpdate("insert into something (id, name) values (:id, :name)")
            int insert({@literal @}BindBean Something something);

            {@literal @}SqlQuery("select id, name from something where id = :id")
            Something findById({@literal @}Bind("id") long id);
        }
    </code>
    <p>
        You obtain an instance of <code>TheBasics</code> via one of three means, the first opens a new
        handle against a DBI instance, the second attaches the object to an already open handle, and the third
        will obtain and release connections on demand against a DBI instance.
    </p>
    <code>
        DBI dbi = new DBI(dataSource);
        Handle handle = dbi.open();

        TheBasics via_open = dbi.open(TheBasics.class);
        TheBasics attached = handle.attach(TheBasics.class);
        TheBasics on_demand = dbi.onDemand(TheBasics.class);
    </code>

    <h1>Closing Objects</h1>
    <p>
        It is important to ensure you close the underlying handle on a sql object if it was opened via the DBI#open in
        particular.
    </p>

    <h1>Mixin Interfaces</h1>
    <p>
        A number of mixin interfaces are included in the org.skife.jdbi.v2.sqlobject package. These provide additional
        functionality on your sql object, such as transactions or access to the underlying Handle instance. To make
        use of them just have your sql object interface extend the mixin interface.
    </p>
</body>
</html>
